home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 5 / Apprentice-Release5.iso / Source Code / Libraries / VideoToolbox 96.06.15 / (Notes) / GWorld baseAddress.doc < prev    next >
Text File  |  1993-12-15  |  7KB  |  130 lines
  1. Note from Apple.
  2. Macintosh GWorld baseAddresses
  3.  
  4. How can I transform the content of a GWorld on a NuBus™ card? The idea is to
  5. clone the GWorld, copy the data to the card, transform them, patch the address
  6. into the GWorld, and display them directly on the screen. I´d like to do it in
  7. a way that works well with the 8•24 GC and similar asynchronous QuickDraw
  8. stuff.
  9. ___
  10.  
  11. NewGWorld allocates off-screen buffers simply by using the same Memory Manager
  12. calls that you and I make. To actually allocate the memory it simply calls
  13. NewHandle to allocate the buffer in your application’s heap if you have the
  14. useTempMem (née useMFTemp) bit clear. It then tries to move it as high in your
  15. heap as possible by calling MoveHHi. If you have the useTempMem bit set, then
  16. NewGWorld uses the temporary memory calls to allocate the off-screen buffer in
  17. temporary memory, and then it tries to move it as high as possible in the
  18. temporary memory space. That’s really all there is to it. The GWorld’s PixMap,
  19. GDevice and CGrafPort are allocated similarly—they’re all allocated in your
  20. heap using regular Memory Manager calls with no special options, patches, or
  21. other nefarious tricks.
  22.  
  23. None of this changes when you have the 8•24 GC software active—all memory is
  24. allocated out of your application’s heap. Once you start drawing into the
  25. GWorld, though, the GC software can copy the parts of a GWorld to the 8•24 GC
  26. memory. The GWorld and its parts go still occupy your heap’s memory though,
  27. regardless of whether it’s cached on the 8•24 GC card or not.
  28.  
  29. If you have a NuBus card with gobs of memory, NewGWorld can’t take advantage
  30. of it because the Memory Manager calls that it uses can’t allocate memory on
  31. NuBus memory cards. There are no options to NewGWorld or any other GWorld
  32. calls that let you say, “there’s lots of memory over on this NuBus card, all
  33. for you.” That means that GWorlds aren’t appropriate if you want to have
  34. control over where the off-screen buffer is allocated. Conceivably, you could
  35. allocate a GWorld, stuff the address of your NuBus memory card into the
  36. baseAddr of your GWorld’s PixMap, and then put the constant baseAddr32 into
  37. its pmVersion field, but engineering here didn’t feel very comfortable with
  38. that idea because of compatibility concerns.
  39.  
  40. QuickDraw is the only thing that’s supposed to know how GWorlds are
  41. constructed. We know that they’re CGrafPorts and we can get their PixMap,
  42. GDevice, and off-screen buffer, but we can’t make any assumptions about how
  43. they were allocated and where they are. For example, we know that the off-
  44. screen buffer is allocated as a handle now, but that won’t necessarily be the
  45. case in the future. There’s no guaranteed way to tell which way it was
  46. allocated, or even if NewGWorld uses the Memory Manager to allocate it at all
  47. (which it always does currently of course). Even the GWorld’s CGrafPort is
  48. allocated as a handle which just happens to be always locked. If you try to
  49. dispose of a GWorld in which you’ve modified the baseAddr, you’ll need
  50. DisposeGWorld to make sure everything is deallocated properly, but it’ll act
  51. unpredictably when it tries to deallocate the off-screen buffer.
  52.  
  53. So if you want to use the memory on your NuBus memory card, you’re going to
  54. have to create your own PixMap, color table (if it needs one), GDevice, and
  55. CGrafPort. Technical Note #120, “Drawing Into an Off-Screen PixMap” covers
  56. creating your own PixMap, CGrafPort, and color table, but it has the same
  57. depth and equivalent color table to the screen, so it just steals a screen’s
  58. GDevice. I think it’s always a good idea to create your own GDevice when you
  59. draw off screen. If you use a screen’s GDevice, then you have to depend on
  60. that GDevice’s depth and color table. By creating your own GDevice, your off-
  61. screen drawing can use any depth and color table you want at any time, and
  62. Color QuickDraw won’t choke.
  63.  
  64. To create your own GDevice, it’s better not to use NewGDevice because it
  65. always creates the GDevice in the system heap, and it’s just better to keep
  66. your own data structures in your own heap. Here’s what you should set each of
  67. its fields to be:
  68.  
  69. gdRefNum     - Your GDevice has no driver, so just set this to zero.
  70.  
  71. gdID         - It doesn’t matter what you set this to; might as well set it
  72.                to zero.
  73.  
  74. gdType       - Set this to 2 if your off screen uses direct colors (16 or
  75.                32 bits per pixel) or 0 if your off screen uses color table
  76.                (1 through 8 bits per pixel).
  77.  
  78. gdITable     - Allocate a small (maybe just 2-byte) handle for this field.
  79.                After you’re done setting up this GDevice and your off-screen
  80.                PixMap, color table (if any) and CGrafPort, then set this
  81.                GDevice as the current GDevice by calling SetGDevice, and then
  82.                call MakeITable, passing it NIL for both the color table and
  83.                inverse table parameters, and 0 for the preferred inverse
  84.                table resolution.
  85.  
  86. gdResPref    - I’d reckon that more than 99.9% of all inverse tables out
  87.                there have a resolution of 4. Unless you have some reason not
  88.                to, I’d recommend the same here.
  89.  
  90. gdSearchProc - Set to NIL. Use AddSearch if you want to use a SearchProc.
  91.  
  92. gdCompProc   - Set to NIL. Use AddComp if you want to use a CompProc.
  93.  
  94. gdFlags      - Set to 0 initially, and then use SetDeviceAttribute after
  95.                you’ve set up the rest of this GDevice.
  96.  
  97. gdPMap       - Set this to be a handle to your off-screen PixMap.
  98.  
  99. gdRefCon     - Set this to whatever you want.
  100.  
  101. gdNextGD     - Set this to nil.
  102.  
  103. gdRect       - Set this to be equal to your off-screen PixMap’s bounds.
  104.  
  105. gdMode       - Set this to -1. Why? I’m not sure. This is intended for
  106.                GDevices with drivers anyway.
  107.  
  108. gdCCBytes    - Set to 0.
  109.  
  110. gdCCDepth    - Set to 0.
  111.  
  112. gdCCXData    - Set to 0.
  113.  
  114. gdCCXMask    - Set to 0.
  115.  
  116. gdReserved   - Set to 0.
  117.  
  118. For gdFlags, you should use SetDeviceAttribute to set the noDriver bit and the
  119. gdDevType bit. You should set the gDevType bit to 1 even if you have a
  120. monochrome color table. The 0 setting was only used for the days when
  121. monochrome mode was handled by the video driver, which 32-Bit QuickDraw
  122. eliminated. Your GDevice doesn’t have a driver anyway.
  123.  
  124. One last warning is that you should set the pmVersion field of your PixMap to
  125. be the constant baseAddr32 (equals 4). That tells Color QuickDraw to use 32-
  126. bit addressing mode to access your off-screen buffer, and that’s a requirement
  127. if your off-screen buffer is allocated on a NuBus card.
  128.  
  129. ©Apple Computer,  Inc.  1985-1991
  130.